---
displayed_sidebar: "Chinese"
---

# date_trunc

## 功能

根据指定的精度级别 `fmt`，将一个日期时间截断。

StarRocks 同时提供 `year()`、`quarter()`、`month()`、`week()`、`day()`、`hour()` 等函数进行指定部分的提取。

## 语法

```Haskell
DATETIME|DATE date_trunc(VARCHAR fmt, DATETIME|DATE datetime)
```

## 参数说明

- `datetime`: 需要截断的时间，类型为 DATETIME 或 DATE。日期和时间必须真实存在，否则返回 NULL。比如 '2021-02-29 11:12:13' 为不存在的日期，计算时会返回 NULL。

- `fmt`: 精度级别，即需要将 `datetime` 截断到哪个时间单位。类型为 VARCHAR 常量。
  
  `fmt` 的取值必须为下表中列举的时间单位。如果取值不正确，则返回报错。

  如果 `datetime` 为 DATE 类型，`fmt` 只支持 `year`，`quarter`，`month`，`week`，`day`，如果设置为其他粒度，会返回报错，参见示例八。

  | fmt 取值   | 含义                                   |
  | --------- | -------------------------------------- |
  | microsecond   | 截断到微秒（3.1.7 及以后）。           |
  | millisecond   | 截断到毫秒（3.1.7 及以后）。           |
  | second        | 截断到秒。                          |
  | minute        | 截断到分钟，秒部分归零。               |
  | hour          | 截断到小时，分钟和秒部分归零。          |
  | day           | 截断到天，时间部分归零。               |
  | week          | 截断到当前星期的第一天，时间部分归零。   |
  | month         | 截断到当前月份的第一天，时间部分归零。   |
  | quarter       | 截断到当前季度的第一天，时间部分归零。   |
  | year          | 截断到当前年份的第一天，时间部分归零。   |

## 返回值说明

返回 DATETIME 或 DATE 类型的值。

## 示例

示例一：将输入的时间截断至微秒。

```plain
select date_trunc('microsecond', '2023-10-31 23:59:59.001002');
+---------------------------------------------------------+
| date_trunc('microsecond', '2023-10-31 23:59:59.001002') |
+---------------------------------------------------------+
| 2023-10-31 23:59:59.001002                              |
+---------------------------------------------------------+
```

示例二：将输入的时间截断至毫秒。

```plain
select date_trunc('millisecond', '2023-10-31 23:59:59.001002');
+---------------------------------------------------------+
| date_trunc('millisecond', '2023-10-31 23:59:59.001002') |
+---------------------------------------------------------+
| 2023-10-31 23:59:59.001000                              |
+---------------------------------------------------------+

select date_trunc('millisecond', '2023-10-31');
+-----------------------------------------+
| date_trunc('millisecond', '2023-10-31') |
+-----------------------------------------+
| 2023-10-31 00:00:00                     |
+-----------------------------------------+
```

示例三：将输入的时间截断至分钟。

```Plain
select date_trunc("minute", "2020-11-04 11:12:13");
+---------------------------------------------+
| date_trunc('minute', '2020-11-04 11:12:13') |
+---------------------------------------------+
| 2020-11-04 11:12:00                         |
+---------------------------------------------+

select date_trunc('minute', '2023-11-04 23:59:59.001002');
+----------------------------------------------------+
| date_trunc('minute', '2023-11-04 23:59:59.001002') |
+----------------------------------------------------+
| 2023-11-04 23:59:00                                |
+----------------------------------------------------+
```

示例四：将输入的时间截断至小时。

```Plain
select date_trunc("hour", "2020-11-04 11:12:13");
+-------------------------------------------+
| date_trunc('hour', '2020-11-04 11:12:13') |
+-------------------------------------------+
| 2020-11-04 11:00:00                       |
+-------------------------------------------+
```

示例五：将输入的时间截断至一周第一天。

```Plain
select date_trunc("week", "2020-11-04 11:12:13");
+-------------------------------------------+
| date_trunc('week', '2020-11-04 11:12:13') |
+-------------------------------------------+
| 2020-11-02 00:00:00                       |
+-------------------------------------------+
```

示例六：将输入的时间截断至季度第一天。

```Plain
select date_trunc("quarter", "2020-11-04 11:12:13");
+----------------------------------------------+
| date_trunc('quarter', '2020-11-04 11:12:13') |
+----------------------------------------------+
| 2020-10-01 00:00:00                          |
+----------------------------------------------+
```

示例七：将输入的时间截断至一年第一天。

```plain
select date_trunc("year", "2020-11-04 11:12:13");
+-------------------------------------------+
| date_trunc('year', '2020-11-04 11:12:13') |
+-------------------------------------------+
| 2020-01-01 00:00:00                       |
+-------------------------------------------+

select date_trunc('year', '2023-11-04 23:59:59.001002');
+--------------------------------------------------+
| date_trunc('year', '2023-11-04 23:59:59.001002') |
+--------------------------------------------------+
| 2023-01-01 00:00:00                              |
+--------------------------------------------------+
```

示例八：DATE 类型下，`fmt` 设置为 `hour`时，返回报错。

```plain
select date_trunc("hour", cast("2020-11-04" as date));

ERROR 1064 (HY000): Getting analyzing error from line 1, column 26 to line 1, column 51. Detail message: date_trunc function can't support argument other than year|quarter|month|week|day.
```

示例九：DATE 类型下，将输入的时间截断至月的第一天。

```plain
select date_trunc("month", cast("2020-11-04" as date));
+-------------------------------------------------+
| date_trunc('month', CAST('2020-11-04' AS DATE)) |
+-------------------------------------------------+
| 2020-11-01                                      |
+-------------------------------------------------+
```
